NetBIOS Custom Control For Visual BasicTM 2.0 & WindowsTM 3.1 Brad Greenway (c)1993 Intelec Systems Corporation, All Rights Reserved Introduction ------------ NetBIOS, an acronym for Network Basic Input/Ouput System, is an application programming interface that facilitates communication between two processes running on the same machine or separate machines connected by a network. NetBIOS was first introduced with the IBM PC Network adapter card in 1984. As is the case with many IBM specifications drafted during the days of the IBM PC, NetBIOS became an immediate industry standard that to this day is supported by most networking providers. The NetBIOS custom control allows you to communicate with disparate machines connected by a local area network using the NetBIOS transport. To use the control, you must have a NetBIOS driver loaded. For Novell (IPX) networks, Novell provides a NetBIOS emulator (NETBIOS.EXE) that tranports NetBIOS packets encapsulated in Novell's IPX packet protocol. It must be loaded before you start Windows. For Lan ManagerTM type networks such as Microsoft Lan Manager, Microsoft Windows For Workgroups, IBM Lan Server, and DEC Pathworks, NetBIOS is the native transport and will automatically be loaded when your network redirector starts. The NetBIOS custom control supports both the "connectionless" datagram links and session links. Using datagrams is similar to mailing a letter to someone. You mail it and with any luck, it reaches its intended recipient, but there is no guarantee of delivery. Using sessions is similar to phoning someone. You make a call and once the call is answered you converse with each message being acknowleded. The NetBIOS custom control is event driven and relieves the application from polling the status of network communication channels. When new data is received from a remote machine, the NetBIOS custom control executes a Visual Basic subroutine allowing the application to service the received information. The NetBIOS custom control also queues events and received data without data loss allowing the application to service network packets only when it is ready. The NetBIOS custom control supports multiple channels allowing the application to have concurrent NetBIOS links with numerous machines on the network. The number of channels and NetBIOS links is only limited by system resources. The NetBIOS custom control supports two property groups. The lan adapter properties group is used to query information about the local lan adapter. The control and channel properties group is used to initialize, activate, and service the NetBIOS links. To learn how to use the custom control, examine the examples that are provided with this package. A complete discussion of NetBIOS and its use is beyond the scope of this document, but there is an excellent reference that we suggest you purchase. The name of the book is "C Programmer's Guide To NetBIOS, IPX And SPX" by W. David Schwaderer. Lan Adapter Properties ---------------------- NameCount(x) This property returns the number of NetBIOS names currently stored in an adapter's name table. The subscript "x" is the lan adapter from which to retrieve the name count. Example: TotalNames = NetNode1.NameCount(1) The above example returns the number of NetBIOS names currently stored in the first lan adapter's name table. NetName(x) This property is used to determine the NetBIOS names that are stored on a local adapter. The subscript "x" is an integer value whose low byte is the lan adapter number and whose high byte is the index into the name table. The return value is the 16 byte name value. Example: Name0$ = NetNode1.NetName( ( 256 * 0 ) + 1 ) The above example returns the first name in the first lan adapter's name table. Example: Name4$ = NetNode1.NetName( ( 256 * 4 ) + 2 ) The above example returns the fourth name in the second lan adapter's name table. Example: Name4$ = NetNode1.NetName( ( 256 * (NetNode1.NameCount(2)-1)) + 2 ) The above example returns the last name in the second lan adapter's name table. CardID(x) This property returns the permanent 6 byte card name of a NetBIOS lan adapter. The subscript "x" is the lan adapter from which to retrieve the ID. Example: CardName$ = NetNode1.CardID(1) The above example retrieves the 6 byte card ID from the first lan adapter. AvailableNCBS(x) This property is used to determine the number of free "NCBs" on a particular lan adapter. The subscript "x" is the lan adapter from which to retrieve the free NCB count. This property is useful for testing whether a particular channel will be able to function efficiently based on NCB availability. Example: Ncbs = NetNode1.AvailableNCBS(1) The above example returns the number of free NCBs on the first lan adapter. AvailableSessions(x) This property is used to determine the number of free "Sessions" on a particular lan adapter. The subscript "x" is the lan adapter from which to retrieve the free session count. This property is useful for testing whether a particular channel will be able to function efficiently based on session availability which is used for NameType(x) = 2. Example: Sessions = NetNode1.AvailableSessions(1) The above example returns the number of free sessions on the first lan adapter. MaximumSessions(x) This property is used to determine the maximum number of "Sessions" that a particular lan adapter will handle. The subscript "x" is the lan adapter from which to retrieve the maximum session count. This property is useful for testing whether a particular channel will be able to function based on session availability which is used for NameType(x) = 2. Example: MaxSessions = NetNode1.MaximumSessions(1) The above example returns the maximum number of sessions that the first lan adapter can handle. MaximumNCBS(x) This property is used to determine the maximum number of "NCBs" that a particular lan adapter can handle. The subscript "x" is the lan adapter from which to retrieve the maximum NCB count. This property is useful for testing whether a particular channel will be able to function efficiently based on NCB availability. Example: MaxNcbs = NetNode1.MaximumNCBS(1) The above example returns the maximum number of NCBs that the first lan adapter can handle. Control And Channel Properties ------------------------------ Channels This property determines the number of channels that the control will need to service. A channel is a conversation between two NetBIOS clients. All other properties are addressed with a property name subscripted with a channel number ranging from 0 to the number of channels minus 1. This property can only be set once after the control is loaded and cannot change until the control is reloaded. If you do not set this property and use any other property of the control then a default of 1 channel is assumed and cannot be changed until the control is reloaded. Example: NetNode1.Channels = 3 Send(x) This property is used to send data to a remote NetBIOS node. The subscript "x" is the channel that needs to send the data. Example: NetNode1.Send(0)="HELLO THERE" The above example sends the string "HELLO THERE" to its remote. Received(x) This property is used to retrieve data from the NetBIOS receive queue. The subscript "x" is the channel number from which to retrieve data. When data is received, the NetBIOS control will call the Visual Basic function NetNode1_ReceiveData with the channel number as an argument. If the property Received(x) is not checked then the custom control starts a timer that calls NetNode1_ReceiveData about every tenth of a second until the received queue is cleared by checking the value of Received(x). Example: Sub NetNode1_ReceiveData( Channel As Integer ) RecData$ = NetNode1.Received( Channel ) End Sub ReceivedFrom(x) This property is used to retrieve the NetBIOS name of the node that sent the datagram that is in the local node's receive queue. The subscript "x" is the channel number from which to retrieve the remote's name. If you wish to use this property you must check it BEFORE you check the Received(x) property which will clear this property. Example: Sub NetNode1_ReceiveData( Channel As Integer ) RecFrom$ = NetNode1.ReceivedFrom( Channel ) RecData$ = NetNode1.Received( Channel ) End Sub ReceivedTime(x) This property is used to retrieve the "tick count" at which time a message was received. This property returns a long integer value corresponding to the number of milliseconds that have passed since Windows was started. If a Windows runs for more than 49 days then this value will wrap to 0. The subscript "x" is the channel number from which to retrieve the message "tick count". This property is useful for statistics and gauging the amount of activity on a particular channel. If you wish to use this property you must check it BEFORE you check the Received(x) property which will clear this property. Example: Sub NetNode1_ReceiveData( Channel As Integer ) RecTime& = NetNode1.ReceivedTime( Channel ) RecFrom$ = NetNode1.ReceivedFrom( Channel ) RecData$ = NetNode1.Received( Channel ) End Sub Event(x) This property is used to retrieve an event from a channel's event queue. The subscript "x" is the channel from which to retrieve the event. An event is any activity (received data,errors,new connection with a remote,lost connection with a remote,etc.) related to a channel. When an event occurs, the NetBIOS control will call the Visual Basic function NetNode1_LinkEvent with the channel number as an argument. If the property Event(x) is not checked then the custom control starts a timer that calls NetNode1_LinkEvent about every tenth of a second until the event queue is cleared by checking the value of Event(x). The event table provides a listing of possible events. Example: Sub NetNode1_LinkEvent( Channel As Integer ) Event% = NetNode1.Event( Channel ) End Sub ReceiveNCBS(x) This property is used to set the number of receive NCBs (or receive datagram NCBS for LinkType = 1 ) that a channel will use once it is active. The subscript "x" is the channel number that you wish to set. If you do not set this value before enabling the channel, a default of 1 will be assumed and cannot be changed until the control is reloaded. Example: NetNode1.ReceiveNCBS(0) = 5 SendNCBS(x) This property is used to set the number of send NCBs (or send datagram NCBS for LinkType = 1 ) that a channel will use once it is active. The subscript "x" is the channel number that you wish to set. If you do not set this value before enabling the channel, a default of 1 will be assumed and cannot be changed until the control is reloaded. Example: NetNode1.SendNCBS(0) = 5 Status(x) This property is used to enable a channel and will contain status information once the channel is enabled. The subscript "x" is the channel that you wish to enable or check the status of. To enable a channel, set the Status property to 1. After enabling a channel, you can check the status of a channel by checking the Status value. Setting the Status property to 0 will disable the channel and delete LocalName from the adapter's local name table. Example: NetNode1.Status(0) = 1 ' Enable Channel 0 Sub NetNode1_LinkEvent( Channel As Integer ) Ev% = NetNode1.Event( Channel ) ' So That This Sub Will ' Not Continue To Be Called Select Case NetNode1.Status(Channel) Case 2 ' NetBIOS Name Has Been Added ' If LinkType = 1 Then Ready To Send ' If LinkType = 2 Then Calling Remote Case 3 ' No Remote Found, Listening Case 4 ' Connected With Remote, Ready To Send End Select End Sub ReceiveBufferSize(x) This property is used to set the size of the receive buffers that a channel will use once it is active. The subscript "x" is the channel number that you wish to set. If you do not set this value before enabling the channel, a default of 512 will be assumed and cannot be changed until the control is reloaded. Example: NetNode1.ReceiveBufferSize(0) = 1024 SendBufferSize(x) This property is used to set the size of the send buffers that a channel will use once it is active. The subscript "x" is the channel number that you wish to set. If you do not set this value before enabling the channel, a default of 512 will be assumed and cannot be changed until the control is reloaded. Example: NetNode1.SendBufferSize(0) = 1024 LinkType(x) This property is used to set the type of link that a channel will use. The subscript "x" is the channel number that you wish to set. Setting this value to 1 causes the channel to send and receive "connectionless" datagrams and setting this value to 2 causes the channel to establish a session with the remote and send and receive with acknowledgment. If you do not set this value before enabling the channel, a value 1 is assumed. It can be changed at any time. Example: NetNode1.LinkType(0) = 2 LinkAttemptFlag(x) This property is used with LinkType = 2 to set the type of link attempt that the channel will use to establish a session with the remote. The subscript "x" is the channel that you wish to set. Setting this value to 1 will cause the channel to issue a NetBIOS "Call" for the remote when the channel is first enabled. If the "Call" fails, then the channel will issue a NetBIOS "Listen" waiting for a "Call" from the remote. Setting this value to 2 will cause the channel to issue repeated NetBIOS "Call"s for the remote. Setting this value to 3 will cause the channel to issue a NetBIOS "Listen" for the remote immediately after the channel is enabled. If you do not set this property before the channel is enabled, then a default of 1 is assumed. It can be changed at any time. Example: NetNode1.LinkAttemptFlag(2) = 3 Lana(x) This property is used to set the lan adapter that a channel will use. The subscript "x" is the channel that use wish to set. If you do not set this property before the channel is enabled, the first lan adapter that supports NetBIOS will be assumed and cannot be changed until the control is reloaded. Example: NetNode1.Lana(0) = 1 The above example tells channel 0 to use the first lan adapter. Example: NetNode1.Lana(0) = 2 The above example tells channel 0 to use the second lan adapter. NameType(x) This property is used to set the type of NetBIOS name that a channel will add and use. The subscript "x" is the channel that you wish to set. Setting this value to 1 will cause the channel to add LocalName as a NetBIOS "local name" (unique). Setting this value to 2 will cause the channel to add LocalName as a NetBIOS "group name" (non-unique). If you do not set this property before the channel is enabled, then a value of 1 is assumed. It can be changed at any time. Example: NetNode1.NameType(0) = 1 LocalName(x) This property is used to set the NetBIOS name that a channel will use to send and receive data. The subscript "x" is the channel that use wish to set. If you do not set this property before the channel is enabled, then a value of "CHANNEL nnn " will be assumed. nnn is the channel number. This property can be changed at any time. Example: NetNode1.LocalName(0) = "CARPATHIA" RemoteName(x) This property is used to set the NetBIOS name that a channel will use to send and receive data. The subscript "x" is the channel that use wish to set. If you do not set this property before the channel is enabled, then a value of "CHANNEL nnn " will be assumed. nnn is the channel number. This property can be changed at any time. Setting this value to "*" with a LinkType = 2 will cause the channel to establish a NetBIOS session with any remote adapter "Calling" LocalName. Example: NetNode1.RemoteName(0) = "CARPATHIA" Control Events -------------- LinkEvent( Channel As Integer ) This event is called each time an event for a channel occurs. An event might be a NetBIOS error or an event listed in the event table. The application should check the value of the Event(Channel) property during this event or the control will continue to call this subroutine every tenth of a second until the Event(Channel) property is checked. Example: Sub NetNode1_LinkEvent( Channel As Integer ) Ev% = NetNode1.Event(Channel) ' This ensures that this ' subroutine will not be called ' again until the next event End Sub ReceiveData( Channel As Integer ) This event is called each time data is received on a particular channel. The application should check the value of Received(Channel) during this event or the control will continue to call this subroutine every tenth of a second until the Received(Channel) property is checked. Example: Sub NetNode1_ReceiveData( Channel As Integer ) Rd$ = NetNode1.Received(Channel) ' This ensures that this ' subroutine will not be called ' again until new data ' is received End Sub SentData( Channel As Integer ) This event is called each time a channel has transmitted data. For LinkType = 2, execution of this event also means that a remote has acknowledged the reception of data. Example: Sub NetNode1_SentData( Channel As Integer ) ' Ready to send next packet on channel Channel End Sub Example Applications -------------------- SAMPLE1.MAK This example application sends datagrams to itself through the NetBIOS driver. Notice that all that is needed to enable a channel is to set the status property to 1. All other properties will assume their default values: Channels 1 LocalName CHANNEL 0 RemoteName CHANNEL 0 ReceiveNCBS 1 SendBufferSize 512 SendNCBS 1 ReceiveBufferSize 512 LinkType 1 Lana 1 (or first adapter) NameType 1 This example waits for the LinkEvent subroutine to be executed. If the Event(Channel) property is set to -1, then the name "CHANNEL 0" has been added to the adapter's local name table and is ready to send and receive data. If the Event(Channel) is a value greater than 0, then a NetBIOS error has occured and channel 0 is disabled. SAMPLE2.MAK & SAMPLE3.MAK These examples establish NetBIOS sessions with each other. The only difference between SAMPLE2.FRM and SAMPLE3.FRM is that in the Form_Load subroutine of SAMPLE2.FRM, LocalName is set to "SAMPLE2" and RemoteName is set to "SAMPLE3" and in the Form_Load subroutine of SAMPLE3.FRM, LocalName is set to "SAMPLE3" and RemoteName is set to "SAMPLE2". Run SAMPLE2.EXE and SAMPLE3.EXE on the same machine or on different machines on the network to test sending and receiving over NetBIOS. SAMPLE4.MAK This example shows how to use all the lan adapter properties. Notice that this example catches a possible error. If a call to the first lan adapter fails then the example uses the second lan adapter. If you are using multiple protocol drivers for your lan adapter such as NDIS or ODI drivers, then sometimes the NetBIOS protocol might be loaded as the second lan adapter even though there is only one adapter. Your applications should always check for this possibility because multiple protocol drivers are increasingly popular. SAMPLE5.MAK This example sends and receives datagrams on two channels of one control. Run multiple copies of SAMPLE5.EXE on different machines on the network and send and receive data to explore the multiple channel feature. SAMPLE6.MAK This example shows how to act as a host for a Symbol TechnologiesTM Spectrum OneTM radio network. A Spectrum OneTM network controller attaches to a network and communicates with its hosts via NetBIOS. The example uses datagrams but could easily be modified to use sessions. SAMPLE7.MAK described below could be modified to do this. SAMPLE7.MAK & SAMPLE8.MAK These samples demonstrate how to use the custom control as a server in a client/server configuration. SAMPLE7.MAK is the server and will host up to 5 clients. Run it first. SAMPLE8.MAK is the client application. Run up to 5 copies of SAMPLE8.EXE on the network, enter unique local names, and watch the clients connect and send to the server. Event Values ------------ Any of the following events will trigger a NetNode1_LinkEvent call. The value returned by Event(Channel) is listed in the left column and its meaning is listed on the right. < 0 Special Control Events ------------------------------ -1 NetBIOS Name Added To Adapter. -2 Connection With Remote Adapter. -3 Data Sent To Remote Adapter. -4 Data Received From Remote Adapter. > 0 NetBIOS Errors ---------------------- 1 Invalid Buffer Length - With LinkType = 1, The maximum SendBufferSize is 512. 6 Incomplete Received Message - For LinkType = 2, ignore this error, you will receive the remaining message later. For LinkType = 1, you have lost part of the message - make the ReceiveBufferSize larger. 9 No Resource Available - For LinkType = 2, The remote lan adapter refused a connection because it is out of resources needed to handle the connection. 10 Session Has Been Closed - For LinkType = 2, the remote lan adapter has closed its connection with a channel. The channel will automatically attempt to re-establish the link based on the value of LinkAttemptFlag. 13 Duplicate Name In Local NetBIOS Name Table - LocalName already existed in the adapter's name table. This is for advisory purposes only. The channel will use the name anyway. 14 NetBIOS Name Table Full - The lan adapter's name table cannot hold anymore names. The channel will not be functional. Refer to your NetBIOS driver's reference manual to increase the adapter's name limit. 17 NetBIOS Local Session Table Full - For LinkType = 2, The lan adapter's session table cannot hold anymore sessions. The channel will not be functional. Refer to your NetBIOS driver's reference manual to increase the adapter's session limit. 18 Session Open Rejected Because No Listen Is Outstanding - For LinkType = 2, The NetBIOS "Call" failed because the remote adapter did not have a "Listen" command pending. 20 Cannot Find Name Or No Answer - For LinkType = 2, The NetBIOS "Call" failed because RemoteName could not be found. This is for advisory purposes only. The channel will proceed based on the value of LinkAttemptFlag. 22 Name In Use On Remote Adapter - The name you specified for LocalName is already registered as a unique name on another adapter. Change LocalName or the channel will not be functional. 24 Session Ended Abnormally - For LinkType = 2, a link was terminated because of a time-out or a hardware problem. This is for advisory purposes only. The channel will proceed based on the value of LinkAttemptFlag. 25 Name Conflict Detected - The NetBIOS driver has detected two or more identical unique names on the network. Disable the channel and specify another LocalName. 33 Interface Busy - The NetBIOS driver is out of resources. Refer to your NetBIOS driver's reference manual for increasing system resources. 34 To Many Commands Outstanding - The NetBIOS drivers does not support the number of NetBIOS commands that you are trying to use. Decrease ReceiveNCBS, SendNCBS, or refer to your NetBIOS driver's reference manual for increasing the maximum number of NCBs that can be outstanding. 37 Reserved Name Specified For Add Name - The name you have specified for LocalName is a NetBIOS reserved name. Change LocalName. Visual Basic Errors ------------------- The following is a list of special errors that can be returned by the NetBIOS custom control. The value in the left column is the error code returned in the Visual Basic "Err" variable and its meaning is on the right. 22187 Channels Is Already Set 22188 Channels Has Not Been Set 22189 ReceiveNCBS Has Not Been Set 22190 ReceiveNCBS Has Already Been Set 22191 BufferSize Has Already Been Set 22192 LinkType Has Already Been Set 22193 NameType Has Already Been Set 22194 LinkType Must Be 1 (Datagram) Or 2 (Session) 22195 NameType Must Be 1 (Local) Or 2 (Group) 22196 Lana Has Already Been Set 22197 Lana Must Be 1 (Primary) Or 2 (Secondary) 22198 Lana Has Not Been Set 22199 LinkType Has Not Been Set 22200 Lana Has Not Been Set 22201 NameType Has Not Been Set 22202 BufferSize Has Not Been Set 22203 BufferSize Must Be Between 1 And 32000 22204 LocalName Has Not Been Set 22205 RemoteName Has Not Been Set 22206 Lana Not Available On This Machine 22207 Invalid Name Number 22208 NetBIOS Name Not Yet Added To Name Table 22209 Not Yet Connected To RemoteName 22210 SendNCBS Has Not Been Set 22211 SendBufferSize Has Already Been Set 22212 SendBufferSize Must Be Between 1 And 32000 22213 SendBufferSize Has Not Been Set 22214 SendNCBS Has Already Been Set 22215 No Send NCBS Are Available 22216 Invalid Status Setting - 0=Disabled 1=Enabled 22217 Invalid LinkAttemptFlag - Use 1, 2, Or 3 Visual Basic is a trademark of Microsoft Corporation. Windows is a registered trademark of Microsoft Corporation IBM is a registered trademark of International Business Machine Registration Form Please take a moment to fill out the registration form and send it back to us. Doing so will speed up your receiving important information such as updates or bug fixes. Please return to: Intelec Systems Corp. Attn: NetBIOS VBX 10201 W. Markham STE 101 Little Rock, AR 72205 or fax to: (501) 221-7412 Name: ___________________________________________ Company Name: ___________________________________________ Street Address: ___________________________________________ ___________________________________________ City/State/Zip Code: ___________________________________________ Telephone: ___________________________________________ Compuserve ID: ___________________________________________ Internet E-mail: ___________________________________________